Purpose:
The datetime module includes functions and classes for doing date and time parsing, formatting, and arithmetic.
Time value are represented with the time class. A time has attributes for hour, minute, second and microsecond and can also include time zone information.
In [1]:
import datetime
t = datetime.time(1, 2, 3)
print(t)
print('hour :', t.hour)
print('minute :', t.minute)
print('second :', t.second)
print('microsecond:', t.microsecond)
print('tzinfo :', t.tzinfo)
datetime min max
In [2]:
import datetime
print('Earliest :', datetime.time.min)
print("Latest :", datetime.time.max)
print("Resolution :", datetime.time.resolution)
Note:
the resolution for time is limited to whole microseconds
In [3]:
import datetime
for m in [1, 0, 0.1, 0.6]:
try:
print('{:02.1f} :'.format(m),
datetime.time(0, 0, 0, microsecond=m))
except TypeError as err:
print('ERROR:', err)
Calendar date values are represented with the date class. Instances have attributes for year, month, and day. It is easy to create a date representing the current date using the today() class method.
In [4]:
import datetime
today = datetime.date.today()
print(today)
print("ctime :", today.ctime())
tt = today.timetuple()
print('tuple : tm_year =', tt.tm_year)
print(' tm_mon =', tt.tm_mon)
print(' tm_mday =', tt.tm_mday)
print(' tm_hour =', tt.tm_hour)
print(' tm_min =', tt.tm_min)
print(' tm_sec =', tt.tm_sec)
print(' tm_wday =', tt.tm_wday)
print(' tm_yday =', tt.tm_yday)
print(' tm_isdst =', tt.tm_isdst)
print('ordinal:', today.toordinal())
print('Year :', today.year)
print('Mon :', today.month)
print('Day :', today.day)
There are also class methods for creating instances from POSIX timestamps or integers representing date values from the Gregorian calendar, where January 1 of the year 1 is 1 and each subsequent day increments the value by 1.
In [5]:
import datetime
import time
o = 733114
print('o :', o)
print('fromordinal(o) :', datetime.date.fromordinal(o))
t = time.time()
print('t :', t)
print('fromtimestamp(t):', datetime.date.fromtimestamp(t))
As with time, the range of date values supported can be determined using the min and max attributes.
In [6]:
import datetime
print('Earliest :', datetime.date.min)
print('Latest :', datetime.date.max)
print('Resolution:', datetime.date.resolution)
Another way to create new date instances uses the replace() method of an existing date.
In [7]:
import datetime
d1 = datetime.date(2008, 3, 29)
print('d1:', d1.ctime())
d2 = d1.replace(year=2009)
print('d2:', d2.ctime())
Future and past dates can be calculated using basic arithmetic on two datetime objects, or by combining a datetime with a timedelta. Subtracting dates produces a timedelta, and a timedelta can be added or subtracted from a date to produce another date. The internal values for a timedelta are stored in days, seconds, and microseconds.
In [8]:
import datetime
print('microseconds:', datetime.timedelta(microseconds=1))
print('milliseconds:', datetime.timedelta(milliseconds=1))
print('seconds :', datetime.timedelta(seconds=1))
print('minutes :', datetime.timedelta(minutes=1))
print('hours :', datetime.timedelta(hours=1))
print('days :', datetime.timedelta(days=1))
print('weeks :', datetime.timedelta(weeks=1))
The full duration of a timedelta can be retrieved as a number of seconds using total_seconds().
In [9]:
import datetime
for delta in [datetime.timedelta(microseconds=1),
datetime.timedelta(milliseconds=1),
datetime.timedelta(seconds=1),
datetime.timedelta(minutes=1),
datetime.timedelta(hours=1),
datetime.timedelta(days=1),
datetime.timedelta(weeks=1),
]:
print('{:15} = {:8} seconds'.format(
str(delta), delta.total_seconds())
)
Date math uses the standard arithmetic operators.
In [10]:
import datetime
today = datetime.date.today()
print('Today :', today)
one_day = datetime.timedelta(days=1)
print('One day :', one_day)
yesterday = today - one_day
print('Yesterday:', yesterday)
tomorrow = today + one_day
print('Tomorrow :', tomorrow)
print()
print('tomorrow - yesterday:', tomorrow - yesterday)
print('yesterday - tomorrow:', yesterday - tomorrow)
A timedelta object also supports arithmetic with integers, floats, and other timedelta instances.
In [11]:
import datetime
one_day = datetime.timedelta(days=1)
print('1 day :', one_day)
print('5 days :', one_day * 5)
print('1.5 days :', one_day * 1.5)
print('1/4 day :', one_day / 4)
# assume an hour for lunch
work_day = datetime.timedelta(hours=7)
meeting_length = datetime.timedelta(hours=1)
print('meetings per day :', work_day / meeting_length)
Both date and time values can be compared using the standard comparison operators to determine which is earlier or later.
In [13]:
import datetime
import time
print('Times:')
t1 = datetime.time(12, 55, 0)
print(' t1:', t1)
t2 = datetime.time(13, 5, 0)
print(' t2:', t2)
print(' t1 < t2:', t1 < t2)
print()
print('Dates:')
d1 = datetime.date.today()
print(' d1:', d1)
d2 = datetime.date.today() + datetime.timedelta(days=1)
print(' d2:', d2)
print(' d1 > d2:', d1 > d2)
Use the datetime class to hold values consisting of both date and time components. As with date, there are several convenient class methods to make creating datetime instances from other common values.
In [14]:
import datetime
print('Now :', datetime.datetime.now())
print('Today :', datetime.datetime.today())
print('UTC Now:', datetime.datetime.utcnow())
print()
FIELDS = [
'year', 'month', 'day',
'hour', 'minute', 'second',
'microsecond',
]
d = datetime.datetime.now()
for attr in FIELDS:
print('{:15}: {}'.format(attr, getattr(d, attr)))
combine date and time
In [15]:
import datetime
t = datetime.time(1, 2, 3)
print('t :', t)
d = datetime.date.today()
print('d :', d)
dt = datetime.datetime.combine(d, t)
print('dt:', dt)
The default string representation of a datetime object uses the ISO-8601 format (YYYY-MM-DDTHH:MM:SS.mmmmmm). Alternate formats can be generated using strftime().
In [16]:
import datetime
format = "%a %b %d %H:%M:%S %Y"
today = datetime.datetime.today()
print('ISO :', today)
s = today.strftime(format)
print('strftime:', s)
d = datetime.datetime.strptime(s, format)
print('strptime:', d.strftime(format))
Within datetime, time zones are represented by subclasses of tzinfo. Since tzinfo is an abstract base class, applications need to define a subclass and provide appropriate implementations for a few methods to make it useful.
datetime does include a somewhat naive implementation in the class timezone that uses a fixed offset from UTC, and does not support different offset values on different days of the year, such as where daylight savings time applies, or where the offset from UTC has changed over time
In [20]:
import datetime
min6 = datetime.timezone(datetime.timedelta(hours=-6))
plus6 = datetime.timezone(datetime.timedelta(hours=6))
print("now:", datetime.datetime.now())
d = datetime.datetime.now(min6)
print(min6, ':', d)
print(datetime.timezone.utc, ':',
d.astimezone(datetime.timezone.utc))
print(plus6, ':', d.astimezone(plus6))
# convert to the current system timezone
d_system = d.astimezone()
print(d_system.tzinfo, ' :', d_system)
The third party module pytz is a better implementation for time zones. It supports named time zones, and the offset database is kept up to date as changes are made by political bodies around the world.
In [ ]: